home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / utilities / powertools.lha / powertools / PowerTools_lib.doc next >
Encoding:
Text File  |  1994-05-01  |  17.1 KB  |  429 lines
  1. TABLE OF CONTENTS
  2.  
  3. PowerTools.lib/--background--
  4. PowerTools.lib/pt_BusyPointer
  5. PowerTools.lib/pt_SimpleRequest
  6. PowerTools.lib/pt_FileRequest
  7. PowerTools.lib/pt_SplitPath
  8. PowerTools.lib/pt_AllocProgress
  9. PowerTools.lib/pt_UpdateProgress
  10. PowerTools.lib/pt_FreeProgress
  11. PowerTools.lib/pt_AllocListRequest
  12. PowerTools.lib/pt_ListRequest
  13. PowerTools.lib/pt_FreeListRequest
  14. PowerTools.lib/--background--   PowerTools.lib/--background--
  15.     PowerTools_lib was created by Bart Vanhaeren.
  16.     ©1993,1994 Quadra development.
  17.  
  18.     
  19.  
  20.     The PowerTools package (lib, includes and docs) are public domain
  21.     and freely distributable. Anyone who programs the Amiga may use
  22.     the PowerTools code for commercial or PD software. A small note in
  23.     the documentation of your software would be appreciated, though.
  24.  
  25.     NOTE #1: THE POWERTOOLS.LIB FILE MAKES CALLS TO THE REQTOOLS.LIBRARY
  26.     WHICH IS ©NICO FRANÇOIS. PLEASE NOTE THAT HIS DEMANDS AND RULES
  27.     ACCORDING TO THE REQTOOLS PACKAGE ALSO STAY EFFECTIVE WHEN YOU USE
  28.     IT THROUGH POWERTOOLS.LIB.
  29.  
  30.     NOTE #2: POWERTOOLS.LIB REQUIRES OPERATING SYSTEM 2.04 OR HIGHER.
  31.  
  32.     NOTE #3: NO WARRANTIES ARE IMPLIED OR EXPRESSED WITH REGARD TO THE
  33.     FITNESS OR MERCHANTABILITY OF POWERTOOLS FOR ANY PARTICULAR PURPOSE.
  34.     ALL RISKS AND DAMAGES, INCIDENTAL OR OTHERWISE, ARISING THROUGH THE
  35.     USE OR MISUSE OF POWERTOOLS ARE ENTIRELY AT THE RESPONSIBILITY OF
  36.     THE USER.
  37.  
  38.  
  39.     What is PowerTools?
  40.     ~~~~~~~~~~~~~~~~~~~
  41.     The PowerTools.lib is a standard Amiga linker-library that contains
  42.     some handy and easy to use C-coded functions. The functions were
  43.     developed and elaborated in a series of programs that I made.
  44.     Because the functions increased the compilation time considerably,
  45.     I thought it was a good idea to put them away in a library.
  46.     This library will grow bigger as I have new and good functions to
  47.     put into it. You can see it as a sort of amiga.lib.
  48.  
  49.     Although most functions in this lib already exist in other (shared)
  50.     libraries, the versions in my lib are easier to use, and very powerful
  51.     too. In fact, this lib uses the existing code in other libraries but
  52.     it also makes the necessary memory allocations and initializations.
  53.     So, you don't have to bother anymore on opening libraries, closing
  54.     them, declaring structures, filling them in, etc...
  55.  
  56.     The functions in the lib are designed to make efficient use of the
  57.     available libraries (e.g. PowerTools.lib uses Kickstart 3.0 features
  58.     if available). Some functions allow you to prefer ReqTools routines
  59.     without being dependant of ReqTools (if ReqTools calls fail, standard
  60.     system routines will be used). This allows you to create very flexible
  61.     and intelligent programs.
  62.  
  63.  
  64.     How to use PowerTools?
  65.     ~~~~~~~~~~~~~~~~~~~~~~
  66.     Currently, PowerTools can only be used within C-programming environ-
  67.     ments. If anyone knows how to make PowerTools available to other
  68.     programming languages, please contact me.
  69.  
  70.     Simply #include the PowerTools.h file (should be placed in INCLUDE:-
  71.     directory) in your C-source. It contains all definitions and prototypes
  72.     to use PowerTools.lib.
  73.     After that, you can call the PowerTools.lib functions like any other C-
  74.     function. Just pass the right parameters and collect the (optional)
  75.     return code, PowerTools does the rest!
  76.  
  77.     After compilation, you must link your program object with the
  78.     PowerTools.lib file. If you use the PT_USERT flag with the PowerTools
  79.     functions, you must also link the reqtools.lib (together with
  80.     PowerTools.lib) with your program. The reqtools development package is
  81.     available from Nico François directly, or from various PD collections.
  82.     The linker (from your C-development package) will attach all used
  83.     PowerTools (and ReqTools) functions to your program. Now you can test
  84.     your program and see if everything works as you expected.
  85.  
  86.     PowerTools.lib opens all it's needed libraries itself, and closes them
  87.     when they aren't needed anymore. This means you don't have to take care
  88.     of opening and closing libraries for PowerTools, but it also means that
  89.     you may *NOT* rely on the libraries PowerTools opened (because PowerTools
  90.     may close them without any notice). If you use the same libraries as
  91.     PowerTools, you should open (and close) them yourself, for private use.
  92.     The only libraries PowerTools expects to be open are the exec.library and
  93.     the dos.library. Both of them should have been opened by the startup-code
  94.     anyway.
  95.  
  96.  
  97.     Thanks to:
  98.     ~~~~~~~~~~
  99.     - Frank Maesen for ß-testing and being the first PowerTools user.
  100.     - Nico François for the great ReqTools.
  101.     - Commodore-Amiga for creating my Amiga 2500/020.
  102.  
  103.  
  104.     Comments, suggestions, bug reports, questions and donations:
  105.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  106.     Quadra Development,
  107.     t.a.v. Bart Vanhaeren,
  108.  
  109.     Weg naar Zwartberg 248
  110.     B-3660 Opglabbeek (BELGIUM)
  111. PowerTools.lib/pt_BusyPointer   PowerTools.lib/pt_BusyPointer
  112.   NAME  
  113.     pt_BusyPointer -- Intelligent busypointer function (V1)
  114.  
  115.   SYNOPSIS
  116.     pt_BusyPointer (window,state);
  117.  
  118.     void pt_BusyPointer (struct Window *,BOOL);
  119.  
  120.   DESCRIPTION
  121.     First checks if running under OS 3.0. If intuition.library V39++ could
  122.     be opened, pt_BusyPointer uses the Workbench busypointer (user defined).
  123.     If OS 3.0 check is negative, this function checks for the presents of
  124.     reqtools.library (any version) and uses its rtSetWaitPointer() function.
  125.     If this doesn't work, the function returns without changing the pointer.
  126.     Window input is blocked by opening an invisible requester on it (V2).
  127.  
  128.   INPUTS
  129.     window - a pointer to the window that should be (un)blocked for mouse input.
  130.     state - TRUE to block input, FALSE to unblock.
  131.  
  132.   NOTE
  133.     Don't forget to call this function twice: the first time to block input and,
  134.     very important, the second time to UNBLOCK the input.
  135.  
  136.   BUGS
  137.     No busypointer when no intuition.library V39 or reqtools.library
  138.     available. No info on this.
  139.  
  140.   SEE ALSO
  141.     intuition.library/SetWindowPointerA() , reqtools.library/rtSetWaitPointer()
  142. PowerTools.lib/pt_SimpleRequest   PowerTools.lib/pt_SimpleRequest
  143.   NAME
  144.     pt_SimpleRequest -- Very easy to use system requester (V1)
  145.  
  146.   SYNOPSIS
  147.     num = pt_SimpleRequest (window,title,textformat,gadgetformat,flags);
  148.  
  149.     LONG pt_SimpleRequest(struct Window *,STRPTR,STRPTR,STRPTR,WORD); 
  150.  
  151.   DESCRIPTION
  152.     This function allocates, interprets and frees everything necessary to
  153.     display a system-requester. If you set the PT_USERT flag,
  154.     pt_SimpleRequest() opens a ReqTools-requester. Otherwise, intuition
  155.     will be used. This function supports multigadget requesters (any number
  156.     of gadgets) and a C-style formatted text string (without arguments).
  157.  
  158.   INPUTS
  159.     window - a pointer to the window the requester should appear on. If you
  160.              pass NULL, the requester opens on the default public screen.
  161.     title - pointer to a title string.
  162.     textformat - C-style formatted string with the body text 
  163.                  (e.g.. "Hello World!\nThis is an example...").
  164.     gadgetformat - string containing all gadgetlabels, each label separated
  165.                    by a '|'-symbol (e.g. "OK|Maby|Cancel").
  166.     flags - Currently supported flags:
  167.  
  168.             PT_USERT: Set if you want reqtools.library to be used.
  169.                       If this fails, the function will fall back
  170.                       on intuition (which should work always...)
  171.  
  172.   RESULT
  173.     Number of gadget that was selected. Note the strange numbering:
  174.     From left to right, the gadgets return number 1, 2, etc.
  175.     The utmost right gadget (the "Cancel" gadget) returns number 0.
  176.  
  177.   NOTE
  178.     This function calls pt_BusyPointer() internally if window ~= NULL.
  179.  
  180.   BUGS
  181.  
  182.   SEE ALSO
  183.     intuition.library/EasyRequestArgs() , reqtools.library/rtEZRequestA()
  184. PowerTools.lib/pt_FileRequest   PowerTools.lib/pt_FileRequest
  185.   NAME
  186.     pt_FileRequest -- Very easy to use file requester (V1)
  187.  
  188.   SYNOPSIS
  189.     ret = pt_FileRequest (window,title,pathbuffer,pattern,flags);
  190.  
  191.     BOOL pt_FileRequest(struct Window *,STRPTR,UBYTE *,STRPTR,WORD); 
  192.  
  193.   DESCRIPTION
  194.     This function allocates, interprets and frees everything necessary to
  195.     display a filerequester. If you set flags to PT_USERT , pt_FileRequest
  196.     opens a ReqTools-requester. Otherwise, an Asl-requester will be used.
  197.  
  198.   INPUTS
  199.     window - a pointer to the window the requester should appear on. If you
  200.              pass NULL, the requester opens on the default public screen.
  201.     title - pointer to a title string.
  202.     pathbuffer - pointer to a stringbuffer which should be at least 108 
  203.                  bytes long
  204.     pattern - pointer to a string that contains a pattern to be used
  205.               in the file-requester. NULL if no pattern required.
  206.     flags - Currently supported flags:
  207.  
  208.             PT_USERT: Set if you want reqtools.library to be used.
  209.                       If this fails, the function will fall back
  210.                       on asl (hope this works !).
  211.  
  212.             PT_SAVEMODE: Set if the requester is used for a save or
  213.                          write operation (strongly advised!).
  214.  
  215.   RESULT
  216.     TRUE if user selected OK (string in pathbuffer is valid), FALSE
  217.     if user canceled requester (do not use pathbuffer contents !).
  218.  
  219.   NOTE
  220.     The allocation and length of the buffers are completely your
  221.     responsibility ! Buffers of less the 108 bytes may lead to serious
  222.     memory trashing (and machine crashing)!!
  223.  
  224.   BUGS
  225.     No filerequester when reqtools.library and asl.library are not
  226.     available. No info on this.
  227.  
  228.   SEE ALSO
  229.     asl.library/AslRequest() , reqtools.library/rtFileRequestA()
  230. PowerTools.lib/pt_SplitPath   PowerTools.lib/pt_SplitPath
  231.   NAME
  232.     pt_SplitPath -- Break a path into a dirname and a filename (V1)
  233.  
  234.   SYNOPSIS
  235.     pt_SplitPath (path,directorybuffer,filenamebuffer);
  236.  
  237.     void pt_Splitpath(STRPTR,UBYTE *,UBYTE *); 
  238.  
  239.   DESCRIPTION
  240.     This function splits a given path into a directoryname and a filename.
  241.     The two name-strings will be copied into the directory and filename
  242.     buffers.
  243.  
  244.   INPUTS
  245.     path - pointer to a legal AmigaDOS path string. (e.g. the one that
  246.            pt_FileRequest creates in your pathbuffer)
  247.     directorybuffer - pointer to a directory buffer which should be at
  248.                       least 108 bytes long.
  249.     filenamebuffer - pointer to a filename buffer which should be at
  250.                      least 108 bytes long.
  251.  
  252.   NOTE
  253.     The allocation and length of the buffers are completely your
  254.     responsibility ! Buffers of less the 108 bytes may lead to serious
  255.     memory trashing (and machine crashing)!!
  256.  
  257.   BUGS
  258.  
  259.   SEE ALSO
  260.     dos.library/FilePart() , dos.library/PathPart()
  261. PowerTools.lib/pt_AllocProgress   PowerTools.lib/pt_AllocProgress
  262.   NAME
  263.     pt_AllocProgress -- Allocate, initialize and render progress indicator (V1)
  264.  
  265.   SYNOPSIS
  266.     progress = pt_AllocProgress (window,xcoord,ycoord,width,height,max,flags);
  267.  
  268.     struct pt_Progress *
  269.          pt_AllocProgress(struct Window *,UWORD,UWORD,UWORD,UWORD,LONG,UWORD);
  270.  
  271.   DESCRIPTION
  272.     This function allocates an pt_Progress structure, fills is with the init-
  273.     values and renders a progress indicator in the window according to the
  274.     guidelines in the Amiga User Interface Style Guide (Commodore-Amiga).
  275.     It returns a pointer to the pt_Progress structure for the indicator.
  276.  
  277.   INPUTS
  278.     window - a pointer to the window the indicator should render in.
  279.     xcoord - X-coordinate of the indicator box. Note that before the box
  280.              a "0% " string will be rendered (leave enough space !).
  281.     ycoord - Y-coordinate of the indicator box.
  282.     width - width of the indicator box. Note that after the box
  283.              a " 100%" string will be rendered (leave enough space !).
  284.     height - height of the indicator box.
  285.     max - maximum level for indicator (= total = 100%), e.g. the total size
  286.           of a file, the total estimated time for a job. This value will
  287.           be used to scale the progress indicator level while updating.
  288.     flags - not used, for future enhancements. Currently always NULL.
  289.  
  290.   RESULT
  291.     A pointer to an initialized pt_Progress structure. This structure
  292.     contains everything the pt_UpdateProgress() function must know
  293.     to adjust the level in the indicator. All fields in this structure are
  294.     private (and subject of change in future) and may only be changed by
  295.     the specific PowerTools functions.
  296.  
  297.   BUGS
  298.     Rendering is based on topaz.8 font and this font is considered as the
  299.     default screen font (and this is not always the case under Release 2++).
  300.  
  301.   SEE ALSO
  302.     pt_UpdateProgress(), pt_FreeProgress()
  303. PowerTools.lib/pt_UpdateProgress   PowerTools.lib/pt_UpdateProgress
  304.   NAME
  305.     pt_UpdateProgress -- Display progress (update) in a progress indicator (V1)
  306.  
  307.   SYNOPSIS
  308.     pt_UpdateProgress (progress,progressvalue);
  309.  
  310.     void pt_UpdateProgress(struct pt_Progress *,LONG);
  311.  
  312.   DESCRIPTION
  313.     Use this function to keep the progress indicator up-to-date. According
  314.     to the progress value you pass, pt_UpdateProgress will render the
  315.     portion of the job that has been processed (in % scale).
  316.     You can call this function at any time, as much as you want. I advise
  317.     you, though, not to call this function after every time a tiny bit of the
  318.     job has been completed. The update routines performs a few (heavy) float
  319.     calculations which require some processor time. I suppose you don't want
  320.     your program calculating on the updating all the time, instead of working
  321.     on your job. A periodic call to this function during the processing of
  322.     the time consuming job should not slow down the performing of your
  323.     program, however.
  324.  
  325.   INPUTS
  326.     progress - pointer to the pt_Progress structure of the indicator.
  327.                pt_UpdateProgress() will update some fields of the struct.
  328.     progressvalue - the absolute amount of the job already finished. This
  329.                     value must always increase (with every call to this
  330.                     function) until it finaly equals to the max value passed
  331.                     in the pt_AllocProgress() function.
  332.                     
  333.   SEE ALSO
  334.     pt_AllocProgress(), pt_FreeProgress()
  335. PowerTools.lib/pt_FreeProgress   PowerTools.lib/pt_FreeProgress
  336.   NAME
  337.     pt_FreeProgress -- Free resources pt_AllocProgress allocated (V1)
  338.  
  339.   SYNOPSIS
  340.     pt_FreeProgress (progress,flags);
  341.  
  342.     void pt_FreeProgress(struct pt_Progress *,UWORD);
  343.  
  344.   DESCRIPTION
  345.     When you do not need the progress indicator anymore, you MUST call this
  346.     function to free all the memory pt_AllocProgress allocated.
  347.  
  348.   INPUTS
  349.     progress - pointer to the pt_Progress structure of the indicator.
  350.     flags - not used, for future enhancements. Currently always NULL.
  351.  
  352.   SEE ALSO
  353.     pt_AllocProgress(), pt_UpdateProgress()
  354. PowerTools.lib/pt_AllocListRequest   PowerTools.lib/pt_AllocListRequest
  355.   NAME
  356.     pt_AllocListRequest -- Allocate and initialize ListRequester (V2)
  357.  
  358.   SYNOPSIS
  359.     listreq = pt_AllocListRequest(window,font,flags);
  360.  
  361.     struct pt_ListRequest *
  362.          pt_AllocListRequest(struct Window *,struct TextAttr *,UWORD);
  363.  
  364.   DESCRIPTION
  365.     Allocates and initializes a pt_ListRequest data structure for you.
  366.  
  367.   INPUTS
  368.     window - pointer to the parent window (you must supply this !).
  369.     font - font to render ListRequest (NULL is not safe!).
  370.     flags - not used, for future enhancements. Currently always NULL.
  371.  
  372.   RESULT
  373.     A pointer to an initialized pt_ListRequest structure. This structure
  374.     must be passed to the pt_ListRequest() function. It is safe to read/
  375.     write the fields in the struct.
  376.  
  377.   SEE ALSO
  378.     pt_ListRequest(), pt_FreeListRequest()
  379. PowerTools.lib/pt_ListRequest   PowerTools.lib/pt_ListRequest
  380.   NAME
  381.     pt_ListRequest -- Get input from user via ListRequester (V2)
  382.  
  383.   SYNOPSIS
  384.     item = pt_ListRequest(listreq,title,list,flags);
  385.  
  386.     WORD pt_ListRequest(struct pt_ListRequest *,STRPTR,struct MinList *,UWORD);
  387.  
  388.  
  389.   DESCRIPTION
  390.     Opens a ListRequester presenting a list of possible choises to the user.
  391.     This function returns when the users makes a choice (returncode >= 0)
  392.     or cancels it (returncode = -1). pt_ListRequest() uses pt_BusyPointer()
  393.     to block all input for the parent Window. It also uses the parent Window
  394.     to find the Screen to open on. The ListRequester is sizeable and font-
  395.     sensitive.
  396.  
  397.   INPUTS
  398.     listreq - pointer to an initialized pt_ListRequest structure.
  399.     title - title string.
  400.     list - pointer to a valid MinList structure to display in the
  401.            requester.
  402.     flags - not used, for future enhancements. Currently always NULL.
  403.  
  404.   RESULT
  405.     Ordinal number of selected item (starting from zero) or -1 if requester
  406.     failed or canceled by user. The selected item (struct node *) can be
  407.     found in the listreq->lr_node field.
  408.  
  409.   SEE ALSO
  410.     pt_AllocListRequest(), pt_FreeListRequest()
  411. PowerTools.lib/pt_FreeListRequest   PowerTools.lib/pt_FreeListRequest
  412.   NAME
  413.     pt_FreeListRequest -- Free resources pt_AllocListRequest allocated (V2)
  414.  
  415.   SYNOPSIS
  416.     pt_FreeListRequest (listreq);
  417.  
  418.     void pt_FreeListRequest(struct pt_ListRequest *);
  419.  
  420.   DESCRIPTION
  421.     When you do not need the ListRequester anymore, you MUST call this
  422.     function to free all the memory pt_AllocListRequest allocated.
  423.  
  424.   INPUTS
  425.     listreq - pointer to the pt_ListRequest structure.
  426.  
  427.   SEE ALSO
  428.     pt_AllocListRequest(), pt_ListRequest()
  429.